feat(reports): add student engagement report API (#64) - #190

Closes #64

Problem Statement (The Bug)

There was no student-engagement reporting surface at all. The platform
stores every input a learning-engagement view needs — LessonProgress
(watchedSecs, completed, updatedAt), Enrollment (progressPercent,
status), UserPoints (currentStreak, longestStreak) — but nothing
reads them back as a summary. Admins and instructors have no way to answer
"how engaged is this cohort?" or "which students have gone quiet?".

This is not a local patch to an existing report: there is no
engagement-report.* module, no route, no aggregation code. It has to be
built as a first-class read model spanning three tables, with scope and
period validation, because ad-hoc per-table queries can't express
cross-table facts like "watch time per student" or "students inactive for N
days".

Solution Comparison and Decision

The Change

New DTO — EngagementReportQueryDto (scope, studentId?, courseId?,
from?, to?, inactiveDays):

export enum EngagementScope { STUDENT = 'STUDENT', COURSE = 'COURSE', PLATFORM = 'PLATFORM' }

New core method — EngagementReportService.getReport(dto). It validates,
resolves the period, pulls the in-scope enrollments once, then fans out:

const [watchAgg, lessonsCompleted, lastActivityByEnrollment, points] = await Promise.all([
  this.prisma.lessonProgress.aggregate({ where, _sum: { watchedSecs: true }, _count: { _all: true } }),
  this.prisma.lessonProgress.count({ where: { ...where, completed: true } }),
  this.prisma.lessonProgress.groupBy({ by: ['enrollmentId'], where, _max: { updatedAt: true } }),
  this.prisma.userPoints.findMany({ where: { userId: { in: studentIds } } }),
]);

Inactivity flagging — per-enrollment last activity
(max(enrollment.updatedAt, max(lessonProgress.updatedAt))) is rolled up to
the student and compared against now - inactiveDays:

const inactive = studentIds.filter((id) => {
  const last = lastActivityByStudent.get(id);
  return !last || last < cutoff;
});

Sample response:

{
  "scope": "COURSE",
  "courseId": "course-1",
  "period": { "from": null, "to": null },
  "generatedAt": "2026-08-27T12:00:00.000Z",
  "summary": {
    "students": 2,
    "enrollments": 2,
    "completedEnrollments": 1,
    "courseCompletionRate": 0.5,
    "avgProgressPercent": 70,
    "watchTime": { "totalSeconds": 7200, "totalHours": 2, "avgSecondsPerStudent": 3600 },
    "lessons": { "started": 10, "completed": 6, "completionRate": 0.6 },
    "streaks": { "avgCurrentStreak": 3, "longestStreak": 12 },
    "inactivity": { "thresholdDays": 14, "inactiveStudents": 1, "inactiveRate": 0.5, "studentIds": ["stu-stale"], "truncated": false }
  }
}

Compatibility Note

No INTERFACE_VERSION constant exists in this repo. The change is purely
additive: one new route, one new DTO, one new service. ReportsModule
gains a controller/provider; the existing ReportsController,
ReportsService and /reports routes are untouched. No schema change, no
migration.

Incidental Fixes

• ReportsModule now exports its providers, so EngagementReportService
  is reusable by other modules (matching the pattern the abuse
  ReportsService already followed).
• Divide-by-zero guards (rate() / round() helpers) so an empty scope
  returns 0 rather than NaN in the JSON.

Testing

src/modules/reports/engagement-report.service.spec.ts — resolves the real
EngagementReportController + EngagementReportService from a Nest module
(Prisma mocked) and calls through controller.getReport(...):

• rejects STUDENT scope without a studentId — FAILED (400) as required
• 404s when the requested student does not exist
• rejects COURSE scope without a courseId
• rejects an inverted reporting period — the adversarial from > to case
• scopes the enrollment query to the course for a cohort report
• summarises watch time, lesson and course completion for a cohort —
  asserts exact aggregate maths (2h watch time, 0.6 lesson completion,
  avg streak 3, longest 12)
• flags students whose last lesson activity is older than the threshold —
  the inactivity adversarial case (one stale, one fresh → exactly one flagged)
• returns a well-formed zeroed payload when there is no data

$ npx jest src/modules/reports/engagement-report.service.spec.ts
Tests:       8 passed, 8 total

Pre-existing, unrelated TypeScript failures in src/modules/reviews/* and
src/modules/uploads/video-transcode.service.ts are present on main and
are not touched here.

Additional Notes

• No base-branch fixup commits.
• Scope: src/modules/reports/ only — one DTO, one controller, one
  service, and the module wiring. No changes to the abuse-report code path,
  to prisma/schema.prisma, or to any other module. Instructor-performance
  reporting ([Backend] Create instructor performance report API #65) is deliberately a separate PR.